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Preface 


The VAX LISP/VMS System Building Guide provides the information needed to 
create executable LISP images with the VAX LISP System-Building Utility on 
VMS systems. 

Intended Audience 

Readers of this manual should have a working knowledge of LISP programming 
and be familiar with the general information about VAX LISP and VMS that 
appears in the VAX LISP /VMS Program Development Guide. 

Document Structure 

This manual consists of three chapters: 

• Chapter 1 provides an overview of the System-Building Utility, the features 
of the user-built system that the utility creates, and the generic procedure for 
using the utility. 

• Chapter 2 describes the define-lisp-system function, which is the center of 
the System-Building Utility, and the arguments to define-lisp-system. 

• Chapter 3 explains how to make the read-only portions of a user-built system 
shareable and how to define a DCL command to invoke a user-built system. 

Associated Documents 

The following documents are relevant to using the VAX LISP/VMS System 
Building Guide : 

• The VAX LISP/VMS Program Development Guide provides general informa¬ 
tion about using VAX LISP and serves as a guide to helpful VAX LISP and 
VMS documentation. 

• The Guide to Setting Up a VMS System gives an overview of some VMS 
utilities that you can use with a user-built LISP executable image. 

• The VAX LISP/VMS Installation Guide explains the VMS Install Utility, 
which you can use to make an executable image shareable. 

• The VMS Command Definition Utility Manual explains the Command 
Definition Utility, which you can use to create a new DCL command for 
invoking an executable image. 


v 




Conventions 

The following conventions are used in this manual: 


Convention 

Meaning 

UPPERCASE 

DCL commands and qualifiers and VMS file names are printed in 
uppercase characters; however, you can enter them in uppercase, 
lowercase, or a combination of uppercase and lowercase characters. 
For example: 

The examples directory (SYS$SYSROOT:[VAXLISREXAMPLES] by 
default) contains sample LISP source files. 

UPPERCASE 

TYPEWRITER 

Defined LISP functions, macros, variables, constants, and other 
symbol names are printed in uppercase TYPEWRITER charac¬ 
ters; however, you can enter them in uppercase, lowercase, or a 
combination of uppercase and lowercase characters. For example: 

The CALL-OUT macro calls a defined external routine .... 

lowercase 

typewriter 

LISP forms are printed in the text in lowercase typewriter 
characters; however, you can enter them in uppercase, lowercase, or 
a combination of uppercase and lowercase characters. For example: 

SANS SERIF 

(setf example-1 (make-space)) 

Format specifications of LISP functions and macros are printed in a 
sans serif typeface. For example: 

CALL-OUT external-routine &REST routine-arguments 

italics 

Lowercase italics in format specifications and in text indicate argu¬ 
ments that you supply; however, you can enter them in lowercase, 
uppercase, or a combination of lowercase and uppercase characters. 
For example: 

The routine-arguments must be compatible with the arguments 
defined in the call to the DEFINE-EXTERNAL-ROUTINE macro. 

( ) 

Parentheses used in examples of LISP code and in format spec¬ 
ifications indicate the beginning and end of a LISP form. For 
example: 

N 

(setq name lisp) 

Square brackets in format specifications enclose optional elements. 
For example: 

[doc-string] 

Square brackets do not indicate optional elements when they are 
used in the syntax of a directory name in a VMS file specification. 
Here, the square bracket characters must be included in the syntax. 
For example: 

{} 

(pathname "MIAMI::DBA1:[SMITH]LOGIN.COM;4") 

In function and macro format specifications, braces enclose elements 
that are considered one unit of code. For example: 

{keyword value } 

{}* 

In function and macro format specifications, braces followed by 
an asterisk enclose elements that are considered one unit of code, 
which can be repeated zero or more times. For example: 

{keyword value}* 





Convention 

Meaning 

&OPTIONAL 

In function and macro format specifications, the word &OPTIONAL 
indicates that the arguments that follow it are optional. For exam¬ 
ple: 

PPRINT object &OPTIONAL stream 

&REST 

Do not specify &OPTIONAL when you invoke a function or macro 
whose definition includes &OPTIONAL. 

In function and macro format specifications, the word &REST 
indicates that an indefinite number of arguments may appear. For 
example: 

CALL-OUT external-routine &REST routine-arguments 

Do not specify &REST when you invoke a function or macro whose 
definition includes &REST. 

&KEY 

In function and macro format specifications, the word &KEY indi¬ 
cates that keyword arguments are accepted. For example: 

COMPILE-FILE input-pathname 

&KEY LISTING :MACHINE-CODE OPTIMIZE 
•.OUTPUT-FILE :VERBOSE WARNINGS 

Do not specify &KEY when you invoke a function or macro whose 
definition includes &KEY. 

A horizontal ellipsis in a format specification means that the ele¬ 
ment preceding the ellipsis can be repeated. For example: 

function-name ... 

| Return | 

A vertical ellipsis in a code example indicates that all the informa¬ 
tion that the system would display in response to the function call 
is not shown; or that all the information a user is to enter is not 
shown. 

A word inside a box indicates that you press a key on the keyboard. 
For example: 

| Return | or |Tab| 

In code examples, carriage returns are implied at the end of each 
line. However, | Return | is used in some examples to emphasize car- 
riage returns. 

| Ctrl/X | 

Two key names enclosed in a box indicate a control key sequence in 
which you hold down Ctrl while you press another key. For example: 

| Ctrl/C| or 1 Ctri/s I 

FFiinn 

A sequence such as |pfi| |_jcJ indicates that you must first press and 
release the key labeled PF1, then press and release another key. 

mouse 

The term mouse refers to any pointing device, such as a mouse, a 
puck, or a stylus. 

MB1, MB2, MB3 

By default, MB1 indicates the left mouse button, MB2 indicates the 
middle mouse button, and MB3 indicates the right mouse button. 
You can rebind the mouse buttons. 

Red print 

In interactive examples, user input is shown in red. For example: 

Lisp> (cdr ' (a b c)) 

(B C) 

Lisp> 
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Chapter 1 

Overview of the System-Building Utility 


The VAX LISP System-Building Utility enables you to create a LISP system that 

is a single executable image. This user-built system can serve as: 

• A customized VAX LISP development environment that can be shared 
efficiently by multiple users at the same time 

• A delivery vehicle for VAX LISP-based applications 

This chapter gives an overview of the System-Building Utility and of the 

user-built system that it creates. The chapter introduces: 

• The purpose of the System-Building Utility, described in terms of the features 
of the LISP system that it creates. 

• The capabilities that the System-Building Utility provides. These capabilities 
are described in terms of the differences between a LISP system created with 
the System-Building Utility and a LISP system created with the VAX LISP 
suspend function. 

• The generic procedure for building a LISP system with the System-Building 
Utility. 

• Prerequisites for using the System-Building Utility. 


1.1 Features of a User-Built System 

The LISP system created by the System-Building Utility consists of a single VMS 

executable (.EXE) file. When you build a LISP system, you have the following 

options: 

• You can exclude certain portions of Digital-provided VAX LISP code from the 
image, thus making the image smaller. Reducing the image size reduces the 
frequency of paging and the requirements for disk space and memory. 

• You can incorporate LISP code that you write into the image. When possible, 
your code is built into read-only sections of the image. The read-only sections 
can be shareable. 

• You can specify the image’s entry point; that is, the main function to be 
executed when the image is invoked. 

• You can specify the size of the image’s dynamic memory and of its control 
stack and binding stack. 
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In addition to these optional features, the user-built system shares the normal 
features of a VMS executable file: 

• You can use the VMS Install Utility to make the read-only portion of the 
image (including the read-only portion of the code you supply) shareable. 
Making the image shareable reduces the physical memory requirements when 
more than one user at a time rims the image. 

• You can invoke the image with the DCL command RUN, which does not 
take LISP-specific qualifiers. (A LISP-specific qualifier is any command line 
qualifier processed by the LISP image.) Alternatively, you can use the VMS 
Command Definition Utility to create a new DCL command for invoking the 
image. The new command can take LISP-specific qualifiers. 

Finally, an important feature of user-built systems is that some systems may be 
distributed to CPUs that have no VAX LISP software license. See Section 2.5 for 
further information on Digital licensing requirements for user-built systems. 


1.2 Differences from a Suspended System 

An executable image created by the System-Building Utility differs from a system 
created by the LISP function suspend in several important respects. A call to 
suspend creates a suspended system with a default file type of .SUS instead of an 
executable image with a default file type of .EXE. (For information on suspend 
and on using suspended systems, see the VAX LISP/VMS Program Development 
Guide,) 

Before Version 2.2 of VAX LISP, only a suspended system enabled you to capture 
a modified LISP environment. Since VAX LISP Version 2.2, your system-building 
options have included two choices: 

• An executable image created with the System-Building Utility 

• A suspended system created from within a user-built system 

This section outlines the differences between the two kinds of systems— 
executable and suspended—that you can create from within VAX LISP. (The 
discussion does not apply to a suspended system created from within a user-built 
executable system.) 

The differences are: 

• A user-built executable image is a stand-alone system; that is, it can run on 
a system on which VAX LISP has not been installed. (However, a user-built 
executable image may require a VAX LISP license to run; see Section 2.5.) 

In contrast, a suspended system can be resumed only in the presence of the 
executable file from which it was suspended—in this case, the VAX LISP 
executable file. Although you can create a suspended system from a user built 
system, it is not possible to suspend the build of a .EXE file and then resume 
it. 

• A user-built executable image can exclude unneeded Digital-provided code. In 
contrast, all Digital-provided code is included in the system that results when 
a suspended system is resumed from VAX LISP. 

• In a user-built executable image, multiple users can share read-only portions 
of both the Digital-provided and user-supplied code; in contrast, they cannot 
share a suspended system. 

A suspended system is useful as a personal, single-user development environment 
and as a way to save some of the state of your work when you need to interrupt 
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an interactive LISP session. A suspended system created from within VAX LISP 
is less useful as: 

• A multiuser customized development environment, because user-written code 
cannot be placed in read-only space and made shareable. 

• A delivery vehicle for user-written applications, because the suspended 
system requires the original executable file in order to resume. 

A user-built executable file is more useful for both these purposes, because it is a 
stand-alone system, because read-only portions of user-written code can be made 
shareable, and because unneeded Digital-provided code can be excluded. 

On the other hand, creating an executable image involves considerably more 
overhead than creating a suspended system. Also, a suspended system saves 
the present LISP environment, while a user-built executable file must build the 
environment from compiled files. 


1.3 Generic System-Building Procedure 

The system-building procedure has two steps: 

1. From within VAX LISP, call the define-lisp-system function. Use keyword 
arguments to specify features of the system. The function define-lisp- 
system creates a VMS command procedure and other files required to build 
your system. 

2. From DCL, execute the command procedure. Commands in the procedure 
build the executable image file. 

You can treat the user-built system like any other VMS executable image. For 
instance, you can install it to make its read-only portions shareable, and you can 
define a special DCL command to invoke it. 

An example of the generic system-building procedure is: 

1. From LISP, call the define-lisp-system function with the desired argu¬ 
ments: 

Lisp> (define-lisp-system "my-program" ... ) 

This step produces a command file named LISP$BUILD-MY-PROGRAM.COM 
and a compiled file named LISP$BUILD-MY-PROGRAM.FAS. 

2. From DCL, execute the command procedure: 

$ @LISP$BUILD-MY-PROGRAM 

This step uses the compiled file (and a number of other special-purpose files) 
to produce an executable file named MY-PROGRAM.EXE. (This step may 
produce a number of linker warning messages, which may be ignored.) 

3. Optionally, use VMS utilities to make the executable file shareable and/or to 
define a new DCL command to invoke the executable file. (See Chapter 3 for 
a description and examples of these steps.) 

4. From DCL, invoke the executable image: 

$ RUN MY-PROGRAM 

The executable image can also be transferred to and used on another CPU 
on which Digital-supplied VAX LISP is not installed. Such a transfer may 
require a Digital software license. (See Section 2.5.) 
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1.4 Preparing to Use the System-Building Utility 

Before using the System-Building Utility, you should make sure that you have 
access to the necessary components of the Digital-supplied VAX LISP kit and that 
your account has an adequate quota of disk space, as described in the following 
sections. 


1.4.1 Digital-Supplied Files 

The command procedure in the System-Building Utility uses the following four 
files, which are supplied with the VAX LISP system: 

• LISP$LIBRARY:LISP$FASLIB.TLB 

• LISP$LIBRARY:LISP$OBJLIB.OLB 

• LISP$LIBRARY:LISP$BUILD-VAXLISP.EXE 

• LISP$LIBRARY:LISP$BUILD-VAXLISP.CLD 

These files must be available to your process. Because only the VAX LISP 
System-Building Utility uses these files, you can save space by removing them 
from your system (leaving them on the Digital distribution medium) when you 
are not using the System-Building Utility. 


1.4.2 Disk Space and Memory 

When you execute the System-Building Utility's command procedure, it starts a 
new LISP process from DCL. It also generates a large number of intermediate 
files that are later deleted and the executable file. 

For you to use the System-Building Utility, your account needs a quota of disk 
space large enough for the command file, the compiled file, and the executable 
file that the utility creates, plus additional blocks for the intermediate files that 
the command procedure generates. The number of blocks that these files require 
depends on options specified with define-lisp-system. Building a full VAX LISP 
system requires approximately 34,000 blocks. 

The virtual memory required to execute the System-Building Utility's command 
procedure includes the virtual memory required by the new LISP process that 
it generates. If you use the VAX LISP spawn function to execute the command 
procedure in a subprocess, your account will require process quotas large enough 
to run two LISP processes simultaneously. 
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Chapter 2 

DEFINE-LISP-SYSTEM Function 


This chapter describes the define-lisp-system function, the center of the 

System-Building Utility. The following sections describe the function and its 

effects: 

• Section 2.1 describes the format of the define-lisp-system function. 

• Section 2.2 shows how to specify the names of the executable image file and 
the files used to build the executable image. 

• Section 2.3 shows how to customize the image by specifying files of user- 
written code to be included in the image, by changing the image's entry point 
(that is, the function that executes when the image starts), and by either 
preventing the standard VAX LISP welcome message from being displayed or 
changing the contents of that message. Section 2.3 also lists restrictions on 
actions that user-written code can perform as it is loaded. 

• Section 2.4 shows how to exclude components of Digital-provided code from 
the image. 

• Section 2.5 shows how to specify whether the image will require a VAX LISP 
software license for distribution. 

• Section 2.6 shows how to specify the default size of the image's dynamic 
memory and the sizes of the control stack and binding stack. 


2.1 Format and Behavior of DEFINE-LISP-SYSTEM 

The define-lisp-system function creates a VMS command procedure and 
returns a string that is the VMS file specification of that procedure. When you 
execute the command (.COM) file from DCL, an executable image containing a 
LISP custom system is produced. 

The define-lisp-system function also creates a compiled (.FAS) file that the 
command procedure uses. The command file and the compiled file remain on your 
system—along with the new executable file—after the system-building procedure 
ends. The format of the define-lisp-system function is shown below. 
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DEFINE-LISP-SYSTEM 


DEFINE-LISP-SYSTEM 


Format 

DEFINE-LISP-SYSTEM image-name 

&KEY :BUILD-FILE-NAMES MNPUT-FILES 
:INIT-FUNCTION :MAIN :HERALD 
:EXCLUDE :REQUIRES-LICENSE :MEMORY 
:BUILD-MEMORY :CONTROL-STACK-SIZE 
:BINDING-STACK-SIZE 


Arguments 

image-name 

A string, symbol, or pathname used to create the name of the executable file and 
(by default) command file and the compiled file. (See Section 2.2.1.) 

:BUILD-FILE-NAMES 

A string, symbol, or pathname used to name the command file and the compiled 
file. (See Section 2.2.2.) 

:INPUT-FILES 

A file specification or a list of file specifications (symbols, strings, or pathnames). 
The file type defaults to .FAS or .LSP, with the more recently created file 
being used in case of a conflict. Code in the files is built into the system. (See 
Section 2.3.1.) 

:INIT-FUNCTION 

A symbol or string that names the function that executes after the welcome 
message (if one is printed) and before the function named by : main or the 
read-eval-print loop. (See Section 2.3.2.) 

:MAIN 

A symbol or string that names the function that executes after the function 
named by : INIT-FUNCTION and whose return terminates the image. The default 
value is the VAX LISP read-eval-print loop. A value of nil specifies this default. 
(See Section 2.3.2.) 

:HERALD 

The value T (the default), nil, or a string specifying whether the standard 
VAX LISP welcome message, no message, or a user-supplied message should be 
displayed when the system starts. (See Section 2.3.2.) 

:EXCLUDE 

A keyword or fist of keywords specifying VAX LISP components to be excluded 
from the system. (See Section 2.4.) 

:REQUIRES-LICENSE 

The value T (the default) or nil, specifying whether the system may run only on 
CPUs with VAX LISP software licenses. (See Section 2.5.) 
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DEFINE-LISP-SYSTEM 


:MEMORY 

An integer specifying, in 512-byte pages, the default total size of the system’s 
dynamic memory when the executable file is invoked. (See Section 2.6.) 

:BUILD-MEMORY 

An integer specifying, in 512-byte pages, the total size of dynamic memory used 
during the build of the executable file. (See Section 2.6.) 

:CONTROL-STACK-SIZE 

An integer specifying, in 512-byte pages, the size of the system’s control stack. 
(See Section 2.6.) 

:BINDING-STACK-SIZE 

An integer specifying, in 512-byte pages, the size of the system’s binding stack. 
(See Section 2.6.) 
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2.2 Naming the Output Files 


The System-Building Utility creates three files that remain on your system after 
the entire procedure is completed. These three files are: 

• A command procedure (.COM file) that is created by the define-lisp-system 
function, then executed to create the customized system 

• A compiled file (.FAS file) that is created by the define-lisp-system function, 
then used by the command procedure to create the customized system 

• An executable file (.EXE file) that is the customized system created by the 
command procedure 

In addition to these three files, the System-Building Utility creates (and later 
deletes) a number of intermediate files that it uses to create the executable file. 

The define-lisp-system function’s image-name argument and :BUILD-file- 
names keyword specify the names of the three permanent output files. Both 
values can be specified as symbols, strings, or pathnames. 

As with all such file specifications in VAX LISP, you can supply a full VMS file 
specification or just a file name. The system supplies default values for any 
other components of a full file specification that you do not supply. (See the VAX 
LISP/VMS Program Development Guide or the VAX/VMS documentation set for 
more information on VMS file specifications.) 


2.2.1 Using the Argument image-name 

The required image-name argument names the executable file that the System- 
Building Utility creates. The file type is .EXE, and the device and directory 
components, if not specified, are the default device and directory when the 
define-lisp-system function is called. 

For instance, the following two examples have equivalent effects: 

(define-lisp-system "diskl:[smith.build]expert.exe") 

and 

(setf (default-directory) "diskl:[smith.build]") 

(define-lisp-system "expert") 

Both examples direct the System-Building Utility to produce an executable file 
with the name: 

DISKI: [SMITH .BUILDJEXPERT.EXE 

By default, the image-name argument also names the command procedure 
and the compiled file that the define-lisp-system function produces. The 
file name specified by image-name is prefixed with LISP$BUTLD-, and the file 
types are .COM and .FAS, respectively. You can supply a value for the keyword 
: build-file-names to override this default. 
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For example, the preceding calls to the define-lisp-system function produce 
“build” files named: 

DISKl:[SMITH.BUILD]LISP$BUILD-EXPERT.COM 

and 

DISK1:[SMITH.BUILD]LISP$BUILD-EXPERT.FAS 

NOTE 

If the value you supply for image-name corresponds to a logical name 
that is currently defined, that logical name is translated and the result 
is used to form the names of the output files. 


2.2.2 Using the :BUILD-FILE-NAMES Keyword 

If you want some or all components of the build file specifications to differ from 
the default, supply a :BUILD-file-names argument. For example: 

(define-lisp-system "diskl:[smith.build]expert.exe" 

:build-file-names 

"diskl:[smith.test]expert-testi") 


or 

(setf (default-directory) "diskl:[smith.build]") 

(define-lisp-system "expert" 

:build-file-names "[smith.test]expert-testi") 

Both calls to the def ine-lisp-system function ultimately produce an executable 
file named: 

DISKI: [SMITH .B UILDjEXPERT.EXE 
The build files, however, are named: 

DISKI: [SMITH .TESTJEXPE RT-TEST1 .COM 
DISKI: [SMITH .TEST]EXPERT-TEST1 .FAS 

If you supply a value for the :build-file-names keyword but do not specify a 
device and/or directory, the build files are placed in the same directory as the 
executable image file. 

You can supply just a device and/or a directory with the : build-file-names key¬ 
word, allowing the file names to be constructed from the image-name argument. 
For example: 

(define-lisp-system "expert" 

:build-file-names "disk2:[smith.test]") 

The two resulting build files are named: 

DISK2:[SMITH.TEST]LISP$BUILD-EXPERT.COM 

DISK2:[SMITH.TEST]LISP$BUILD-EXPERT.FAS 
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The disk on which the build files are placed must also have room for a number 
of other files that are needed to build the system. The total size of these files is 
about 34,000 blocks for a full VAX LISP system. 

The examples in this section illustrate only the name-related arguments to 
the DEFINE-LISP-SYSTEM function. Since they do not change image contents 
or behavior in any way, these examples produce an executable image that is 
functionally identical to the Digital-supplied VAX LISP. 


2.3 Customizing the Image 

lb customize the content and the behavior of the user-built system, use the 
: input-files, : init-function, :main, and :herald keywords. The values of 
these keywords specify the following items: 

• : input-files —File(s) of user-written code to be built into the image 

• : init-function —The function that executes after the welcome message and 
before the function named by :MAIN or the read-eval-print loop 

• :MAIN —The function that executes after the function named by : init- 
function and whose return terminates the image 

• : herald —The presence of the standard message “Welcome to VAX LISP, 
Vx.x,” a user-supplied message, or no message when the image starts 


2.3.1 Using the Keyword :INPUT-FILES 

The : input-files keyword specifies one or more files of LISP code to be built 
into the image. The value of : input-files is a file specification or a list of file 
specifications. A file specification can be a symbol, a string, or a pathname. The 
files you specify are loaded into the image in the order you list them. 

Using the : input-files keyword to include user-written code in an image is like 
using the load function to load code into a running VAX LISP system, with two 
important differences: 

• Code included in a user-built system with the ! input-files keyword becomes 
part of the image file; code loaded into a running system with the load 
function must be in a separate file. 

• Portions of the code that you supply with the : input-files keyword are 
placed in read-only sections of the image; for example, parts of compiled 
function definitions are placed in read-only sections. In contrast, code loaded 
into a running system with the load function can never be placed in read-only 
sections. 

You can include some user-written development tools in the image to create a 
customized VAX LISP development environment. For example: 

(setf (default-directory) "diskl:[smith]") 

(define-lisp-system 
"graphics-lisp" 

:input-files '("editor-extensions" 

"disk2:[jones]graphics-editor" 

"menu-package")) 

The image ultimately produced by this call to define-lisp-system contains three 
files of user-written code. 
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You can also use : input-files to create a customized execute-only system for 
distribution to other VAX CPUs. (See Section 2.5 for information on execute-only 
systems.) 

The define-lisp-system function provides defaults for any file specification 
components that are not supplied in the argument. The file type defaults to .FAS 
or to .LSP. If two files differ only in their file types, : input-files uses the most 
recently created file. In this respect, : input-files behaves just like the load 
function. 

Files specified with the : input-files function can contain calls to the load 
function. Thus, one file specified with : input-files can actually bring many files 
into the image; this is a convenient alternative to entering a long list of files with 
: input-files. If you use load in this way, the code included in the system is still 
placed in read-only space whenever possible. 

In general, files specified with : input-files can contain any VAX LISP code. 
However, you should observe the following restrictions and guidelines: 

• While they load, the files must not create a static alien structure that 
contains pointer fields. (However, the files can contain code that creates such 
structures after the image starts.) 

• Any data structures with pointers to them, for example, an array that is 
the value of a symbol, become part of the image, even if they are not useful. 
Therefore, be sure that only useful data structures are still accessible when 
all your code has been executed. Data structures with no pointers to them 
will be garbage-collected before the image is built. 

• When the image starts, certain aspects of its state are lost, in the same 
way that a suspended system’s state is lost when it resumes. In particular, 
streams that were left open when the system was built are closed, and callout 
state may be lost. (See the description of the suspend function in the VAX 
LISP /VMS Object Reference Manual for more information.) 

• Callout initialization occurs each time the image is run, even if the input files 
caused callout initialization to occur before the system was built. As a result, 
the first use of CALL-OUT in the image causes a short delay while callout 
initialization takes place. 


2.3.2 Using the :MAIN, :INIT-FUNCTION, and :HERALD Keywords 

In a system that is intended to be a delivery vehicle for a user-built application, 
you may want either to change the entry point and the welcome message 
or to perform some computation after the welcome message but before the 
read-eval-print loop starts. 

The value of the :INIT-function keyword specifies the function that executes 
after the welcome message and before either the read-eval-print loop or the 
function specified by the value of the :MAIN keyword. If you omit the :INIT- 
Function keyword or the value of : init-function is nil, the value of the :MAIN 
keyword specifies the function that executes when the image starts. 

When the function specified by : init-function returns, either the read-eval- 
print loop or the function specified by the value of the :MAIN keyword executes. 
When the function specified by the value of the : main keyword returns, the image 
terminates. Therefore, the functions you specify with the : init-function and 
: main keywords control the operation of the system. 
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: init-function or :MAIN must perform system initialization when they start, and 
: main must perform any necessary cleanup before it exits. The function specified 
by the value of the : init-function keyword will not run if the /COMPILE 
command line qualifier is present and the compiler has not been excluded. (See 
Section 3.2.2.3 for further information.) If you omit the :MAIN keyword, or if you 
specify a value of nil with the :MAIN keyword, the VAX LISP read-eval-print loop 
executes and controls the operation of the system. 

The values of the :MAIN and : init-function keywords can be symbols or 
strings. A string is interpreted as the name of a symbol that names the function. 
Specify only a single symbol. The symbol must exist in the system that is 
being built, but it need not be defined in the system in which you are using the 
DEFINE-LISP-SYSTEM function. 

Ib specify a function in a package that does not exist in the VAX LISP system 
from which you are calling define-lisp-system, use a string argument to : init- 
function or :MAIN. However, the package must exist in the system that results 
from the define-lisp-system call. For example: 

(define-lisp-system 

"expert” 

:input-files '("expert-system" "[jones]expert-rules") 

:main "expert-tools:expert-command-loop") 

The package expert-tools need not exist when this call to define-lisp-system 
is made, but the files specified with the : input-files keyword must create the 
package expert-tools and define the expert-command-loop function in that 
package, so that expert-tools : expert-command-loop exists in the new system. 

The default package for a function name you specify with the : init-function 
or : main keyword depends on whether you use the symbol or string form of the 
argument. If you use the symbol form, the default package is the current package 
when the symbol is read. If you use the string form, the default package is 
always the user package. 

If you use the :MAIN keyword to specify a function, that function processes all 
the command line qualifiers. If you define a DCL command to invoke the system 
after having specified a function with the :MAIN keyword, you have to write LISP 
code to process them. (See Section 3.2.2.3 for more information.) 

The value of the : herald keyword controls whether the standard VAX LISP 
welcome message, a user-supplied message, or no message is printed when the 
image starts. The default value of the symbol t requests the standard message: 

Welcome to VAX LISP, Vx.x 

When the value of : herald is a string, that string prints as the welcome message. 
A value of nil suppresses this message. 

The following example demonstrates the use of the :MAIN and : herald keywords: 

(define-lisp-system 

"expert" 

:input-files '("expert-system" "[jones]expert-rules") 

:herald nil 

:main 'expert-command-loop) 

The image eventually produced by this call includes code from two files. When 
this image starts, it does not print the standard VAX LISP welcome message, 
and the function it calls is expert-command-loop. When the value of the expert- 
command-loop function returns, the image terminates. 
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2.4 Excluding Digital-Supplied Code 

You can use the : exclude keyword to prevent certain parts of standard VAX 
LISP from becoming part of your image. When you exclude code from the 
image, the image takes less space on disk and has smaller memory and run-time 
requirements. 

The value of the : exclude keyword is a keyword or list of keywords. Each 
keyword specifies a part of VAX LISP to exclude from your image. Table 2-1 
lists the values for the keyword : exclude. With each value, the table lists the 
component(s) of Digital-supplied code that are excluded from the image when that 
value is specified and the approximate amount of disk space saved. 

Some components of VAX LISP are automatically excluded from systems defined 
with : requires-license nil. These components are noted in Table 2-1. (See 
Section 2.5 for more information.) 


Table 2-1: Values for the Keyword :EXCLUDE 


Value 

Approx. 

Savings 

in 

Blocks 

Component Excluded from the Image 

:ALIEN 

128 

The resulting image loses the ability to define 
new alien data structures. 

:BITBLT 

128 

The BITBLT function, which allows you to alter 
bitmaps. 

:CALLOUT 

6912 

The Call-Out facility, which lets you call routines 
written in other languages. Excluding the 
Call-Out facility precludes the built system 
from using the DECwindows interface and also 
excludes: 

: CLX 

:DWT 

:DECW-DEVELOPMENT-ENVIRONMENT 

: CLX 

4224 

A package of LISP routines that give you access 
to the capabilities of the X Window System 
without having to call out to external routines 
or to define non-LISP data structures. The 
resulting image can still have a programming 
environment including the Editor and the 
DECtoolkit (DWT). 

:COMPILE-FILE 

varies 

The VAX LISP COMPILE-FILE function, which is 
automatically excluded by : REQUIRES-LICENSE 
NIL. (See Section 2.5.2.) 

:COMPILER 

2430 

The VAX LISP Compiler. This precludes using 
the VAX LISP functions COMPILE and COMPILE- 

FILE. 


(continued on next page) 
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Table 2-1 (Cont.): Values for the Keyword :EXCLUDE 


Approx. 

Savings 

in 

Value Blocks Component Excluded from the Image 

: DEBUGGER 1920 The VAX LISP Debugger, and the STEP, 

TRACE, and INSPECT functions. The VAX 
LISP Debugger is automatically excluded by 
:REQUIRES-LICENSE NIL (see Section 2.5.2) and 
by any of the following values to the keyword 
:EXCLUDE: 


:DECW-DEVELOPMENT-ENVIRONMENT 2304 


:DECWINDOWS 4224 


DEFINE-LISP-SYSTEM 

128 

DEFMACRO 

128 

DWT 

2560 

EDITOR 

2302 


:EVAL 
: MACROS 
:REPLOOP 

You cannot use the VAX LISP Debugger as 
a DECwindows-based utility if you spec¬ 
ify : DECWINDOWS, DECW-DEVELOPMENT- 
ENVIRONMENT, or : CALLOUT as a value for 
the : EXCLUDE keyword. (See Section 2.5.2.) 

The DECwindows-based functionality including 
the Inspector, Listener, and DECwindows Help, 
and the DECwindows interface to the Debugger 
and Editor. : DECW-DEVELOPMENT-ENVIRONMENT 
is automatically excluded by : DECWINDOWS. 

The DECwindows interface and DECwindows- 
based utilities—the Listener and the Inspector. 
Including : DECWINDOWS as a value for the 
keyword : EXCLUDE also excludes: 

: CLX 
: DWT 

:DECWINDOWS-DEVELOPMENT-ENVIRONMENT 

The DEFINE-LISP-SYSTEM function. The 
resulting image cannot build another LISP 
system. The DEFINE-LISP-SYSTEM function is 
automatically excluded by : REQUIRES-LICENSE 
NIL. (See Section 2.5.2.) 

The DEFMACRO macro. 

The DECtoolkit. The resulting image cannot 
build any DECwindows applications. 

The VAX LISP Editor. This precludes using the 
ED function or any functionality in the EDITOR 
package. The VAX LISP Editor is automatically 
excluded by : REQUIRES-LICENSE NIL (See 
Section 2.5.2.) 


(continued on next page) 
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Table 2-1 (Cont.): Values for the Keyword :EXCLUDE 


Value 

Approx. 

Savings 

in 

Blocks 

Component Excluded from the Image 

: EVAL 

6784 

The evaluator. Including :EVAL as a value to 
the keyword : EXCLUDE precludes the resulting 
image from using the following items: 

DECwindows interface 

Read-eval-print loop 

Compiler 

Editor 

Debugging utilities 
— Debugger 
— Stepper 
— Tracer 
— Inspector 

: MACROS 

4224 
& More 

Macroexpander functions. These functions 
are created by DEFMACRO and used when a 
macro is invoked from interpreted code and 
when the macro is compiled. Since macro 
invocations in compiled code are fully expanded, 
a system containing only compiled code needs no 
macroexpanders. 

:ORPHAN-SYMBOLS 

Varies 

VAX LISP-created symbols that are never 
referenced. (These symbols exist as a result 
of building the system or excluding parts of 

VAX LISP, but they have no further use.) User- 
created symbols are not affected. The resulting 
image is identical in functionality to one that 
does not exclude : ORPHAN-SYMBOLS, but takes 
up less space. However, it takes longer to build. 

:RANDOM 

128 

Random number generators. 

:REPLOOP 

1024 

The VAX LISP read-eval-print loop. If you 
exclude the read-eval-print loop, you must use 
the :MAIN keyword to specify a function to 
execute when the image starts. The read-eval- 
print loop is excluded by : REQUIRES-LICENSE 
NIL. (See Section 2.5.2.) 

: SORT 

128 

The SORT and STABLE-SORT functions. 

:SUSPEND 

128 

The SUSPEND function. The SUSPEND function 
is excluded by : REQUIRES-LICENSE NIL. (See 
Section 2.5.2.) 


(continued on next page) 
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Table 2-1 (Cont.): Values for the Keyword :EXCLUDE 


Value 

Approx. 

Savings 

in 

Blocks 

Component Excluded from the Image 

:TRANSCENDENTAL 

128 

The transcendental math functions: 

EXP LOG SQRT CIS 

SIN ASIN SINH ASINH 

COS ACOS COSH ACOSH 

TAN ATAN TANH ATANH 

(Space savings may be greater in future re¬ 
leases.) 

: UIS 

1152 

The VAX LISP UIS graphics functionality. This 
precludes using any functionality in the UIS 
package, but not in the CLX graphics interface. 

:VMS-DEBUG 

270 

The VMS-DEBUG function. (See the VAX 

LISP /VMS System Access Guide for a description 
of the VMS-DEBUG function.) The VMS-DEBUG 
function is excluded by : REQUIRES-LICENSE 
NIL. (See Section 2.5.2.) 

:WSSTREAM 

640 

The VAX LISP window stream facility. (See 
Chapter 4 of VAX LISP Implementation and 
Extensions to Common LISP.) 


2.5 Making an Execute-Only System 

Since the System-Building Utility can create a complete VAX LISP programming 
environment, the distribution of some user-built systems is restricted. The basic 
principle is: 

• If a user-built system can be used for creating new VAX LISP programs, its 
use on another CPU requires a valid VAX LISP software license. Such a 
system is called a development system in this manual. 

• If a user-built system is not useful as a VAX LISP programming environment, 
it may be transferred to another CPU without a VAX LISP software license. 
Such a system is called an execute-only system in this manual. 

The value of the keyword requires-license determines whether a user-built 
system is a development system and whether the user-built system can be 
transferred to a CPU without a VAX LISP software license. 


2.5.1 Development Systems 

If the value of the keyword : requires-license is T (the default), you may not use 
a user-built system without a valid VAX LISP software license. This requirement 
holds no matter which components of VAX LISP you have excluded with the 
keyword : exclude. 
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An example of a development system is the user-built expert system created by 
the following call: 

(define-lisp-system 
"expert" 

:input-files '("expert-system" "[jones]expert-rules") 
rherald nil 

:main 'expert-command-loop 
rexclude '(reditor :uis)) 

The file EXPERT.EXE that ultimately results from this form is created with the 
value T for :REQUIRES-license. EXPERT.EXE may not legally be used on a CPU 
that does not have a valid VAX LISP software license. 


2.5.2 Execute-Only Systems 

Tb make the above user-built system execute-only, you would write the following: 

(define-lisp-system 
"expert" 

:input-files '("expert-system" "[jones]expert-rules") 

:herald nil 

:main 'expert-command-loop 
rexclude '(reditor ruis) 

:requires-license nil) 

Because the value of the keyword : requires-license is nil, this system may be 
freely distributed. 

If the value of : requires-license is nil, the user-built system will not contain 
the following components of Digital-provided code. The components correspond to 
the : exclude keyword in parentheses, when such a keyword exists: 

• The VAX LISP debugging facilities (: debugger and -.vms-debug) 

• The VAX LISP Editor (: editor) 

• The VAX LISP System-Building Utility (: def ine-lisp-system) 

• The VAX LISP function compile-file (r compile-file) 

• The VAX LISP read-eval-print loop : rep loop 

• The VAX LISP function suspend (r suspend) 

• The VAX LISP functions time, describe, inspect, disassemble, dribble, 
trace, step, room, apropos, and apropos-list 

If you have not already excluded these components with the keyword : exclude, 
def ine-lisp-system with : requires-license nil will exclude them. While 
def ine-lisp-system is executing, it displays warnings that identify the VAX 
LISP components being excluded because : requires-license is nil. 

NOTE 

Tb create a user-built execute-only system, you must specify : requires- 
license nil no matter which system components you have excluded 
with :exclude. 
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2.6 Specifying Memory Requirements 


The : memory keyword specifies the default size of a user-built system's dynamic 
memory; it is equivalent to the LISP command’s /MEMORY qualifier. The value 
of the : memory keyword is the total size of LISP’s dynamic memory, in 512-byte 
pages. The default size is 5000 pages; the minimum size is 2000 pages. 

You can use the room function to find out how much dynamic memory your system 
is using at any time. VAX LISP’s dynamic memory space is divided into sections 
known as areas. Use the room function to print information about dynamic space. 
By default, a garbage collection occurs whenever 50% or more of the dynamic 
memory has been consumed. You can change this ratio by using setf with the 
DYNAMIC-SPACE-RATIO function. 

To determine a value for the .-memory keyword, build a trial system with the 
default size; then, start the system and use the room function to see how much 
dynamic memory the system consumes. As you use the system, use room from 
time to time to see how quickly dynamic memory is consumed. Also note the 
frequency of garbage collection. Frequent or nearly continuous garbage collection 
activity indicates insufficient memory and a larger value for the : memory keyword 
is in order. 

When you set a default value for dynamic memory, remember the following 
points: 

• A smaller dynamic memory size leads to faster but more frequent garbage 
collections. 

• A larger dynamic memory size leads to slower but less frequent garbage 
collections. A large dynamic memory also requires more virtual memory and 
may cause more paging. 

The default dynamic memory size you specify can be overridden when your image 
is invoked, if you define a DCL command with the /MEMORY qualifier to start 
the image. (See Section 3.2.2 for more information.) 

The : build-memory keyword specifies the size, in 512-byte pages, of the amount 
of memory used during the build. A normal build requires 50,000 pages. If you 
specify fewer pages, the build will take longer. 

The : control-stack-size and : binding-stack-size keywords specify the size, 
in 512-byte pages, of the image’s control and binding stacks. The default for 
:control-stack-size is 185 pages; the minimum size is 32 pages. The default 
for : binding-stack- si ze is 62 pages; the minimum size is 16 pages. 

The sizes required for the control and binding stacks are a rough function of 
the complexity of your system. Highly recursive systems require larger control 
stacks. 

One way to determine whether you should increase stack sizes is to build a test 
system with the default stack sizes. If the stacks overflow in normal operation, 
increase the sizes. (Control stack overflows are treated as errors; binding stack 
overflows are handled automatically, and program execution continues.) 
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Chapter 3 

Working with User-Built Systems 


A user-built system can be treated like any other VMS executable image. This 
chapter describes: 

• Installing the image to allow sharing of read-only code 

• Invoking the image 


3.1 Installing the Image 

If you intend the user-built system to be run concurrently by several processes, 
it is worthwhile to install the image as shareable. Installing an image improves 
performance and reduces the requirements for physical memory in the following 
ways: 

• An installed image is permanently “open,” which means that directory 
information on the image file remains permanently resident in memory. An 
open image does not require the usual directory search to locate the file. 

• When an image is installed as shareable, only one copy of its read-only 
sections need be in physical memory. These global sections can be accessed by 
more than one user at a time. 

The VMS Install Utility installs an executable image, allowing you to make 
the image open as well as shareable. This utility is described in the VAX/VMS 
documentation set: VMS Install Utility Manual and Guide to Setting Up a VMS 
System. 

To install the image: 

1. Invoke the VMS Install Utility. 

2. Execute the CREATE command with the /SHARED qualifier. (/SHARED also 
installs the image as permanently open.) 

3. Exit the VMS Install Utility. 

For example, to make the user-built system MY-LISP.EXE shareable, you would 
do the following: 

1. Invoke the VMS Install Utility. If you are adding a new image to an 

established VMS system, it is probably most convenient to invoke the utility 
in interactive mode. To do so, type: 

$ INSTALL := $SYS$SYSTEM:INSTALL 
$ INSTALL/COMMANDMODE 
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2. At the VMS Install Utility prompt, execute the CREATE command with the 
/SHARED qualifier. The parameter is the name of the executable file. If you 
omit the device and directory, they default to those indicated by the logical 
name SYS$SYSTEM. The default file type is .EXE. 

INSTALLS CREATE/SHARED DI3K1:[SMITH.BUILD]MY-LISP 

This step establishes global sections of the specified executable file’s read¬ 
only contents and makes it permanently open. You need not specify the 
/OPEN qualifier, since an image installed as shareable is also installed as 
permanently open. 

3. If you later want to delete the global sections associated with the image, use 
the VMS Install Utility’s DELETE command. 

INSTALL> DELETE DISKI:[SMITH.BUILD] MY-LISP 

This command removes any global sections created for the image MY- 
LISPEXE. The image file itself is not affected by this operation. 

4. Type either of the following commands to exit the VMS Install Utility: 

INSTALL> EXIT 
INSTALL> [CtrT/Z] 

See the VMS documentation set for further information on the VMS Install 
Utility, especially for other qualifiers to the Install command CREATE. 


3.2 Invoking the Image 

There are four ways to invoke a user-built system: 

• The DCL RUN command 

• A user-defined foreign command 

• A user-defined DCL command 

• The Digital-defined DCL LISP command 

If you use RUN or a foreign command, you cannot use LISP-specific command¬ 
line entities; that is, you cannot use command qualifiers, parameters, or keywords 
processed by the LISP image. With a specially defined DCL command—either 
user-defined or Digital-defined—you can use LISP-specific command-line entities 
with certain restrictions. 

This section discusses these four methods of invoking a user-built system. 

For each method, the section identifies the restrictions, if any, on the use of 
LISP-specific command-line entities. 


3.2.1 Using RUN or a Foreign Command 

You can invoke a user-built LISP system like any VMS executable image with 
either a RUN command or a user-defined foreign command. For example: 

$ RUN MY-LISP 

or 

$ MYLISP := $DISK1:[SMITH.BUILD]MY-LISP 
$ MYLISP 
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See the VMS DCL Dictionary for more information on the RUN command and on 
the facility for defining foreign commands. 

When you use RUN or a foreign command to invoke a LISP image, the LISP 
image cannot call back to DCL to check for the presence of qualifiers or other 
command-line entities. For this reason, you cannot use any LISP-specific 
qualifiers, such as /MEMORY, with RUN or a foreign command. 


3.2.2 Defining a DCL Command 

You can use the VMS Command Definition Utility (CDU) to create a new DCL 
command that invokes a user-built system. This command can be used with 
or without LISP-specific command-line entities. The CDU is described in the 
VMS Command Definition Utility Manual. This section assumes that you are 
generally familiar with DCL command definition and with writing code to retrieve 
command string information. 

The procedure for creating a DCL command is: 

1. Write a command language definition (CLD) file that defines the command 
and its qualifiers, parameters, and keywords, if any. 

2. Be sure that the image to be invoked by the command contains code that calls 
back to DCL to check for the presence of each such qualifier, parameter, or 
keyword, then responds appropriately. 

3. Use the DCL command SET COMMAND to add your CLD file to the system 
command table or to an individual process command table. 

4. Log out and log in again to make the command available. (This step is not 
necessary if you used SET COMMAND to add the CLD file to your own 
process command table.) 

The Digital-provided VAX LISP image contains code that checks for and processes 
the Digital-defined qualifiers to the LISP command. (The VAX LISP/VMS 
Program Development Guide lists and describes these qualifiers.) A user-built 
system contains all or part of the Digital-provided VAX LISP. Therefore, in 
defining a DCL command to invoke a LISP image, you face some restrictions 
when choosing qualifier names, and you may have to redefine some Digital- 
defined qualifiers. In general terms, the restrictions are: 

• If your user-built system contains the Digital-provided code that checks 
for a given qualifier and you want to use that qualifier when invoking the 
system, your CLD file must define the qualifier exactly as it is defined in 
LISP$SYSTEM:LISP.CLD, the file that defines the DCL LISP command. If 
you do not want to use the qualifier, your CLD file need not define it. 

• If your user-built system does not contain the Digital-provided code that 
checks for a given qualifier, you can define that qualifier in any way you like. 
However, your image must include user-written code to check for the qualifier. 
(See Sections 3.2.2.2 and 3.2.2.3 to determine whether your image contains 
code that checks a given qualifier.) 

• Qualifiers with names that are not defined by Digital as qualifiers to the LISP 
command—and all other command-line entities—can be defined in your CLD 
file in any way you like. You must, however, include user-written code in your 
image to check for each such entity. 
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To check for the presence of command-line entities, use the VAX LISP functions 
COMMAND-LINE-ENTITY-P and COMMAND-LINE-ENTITY-VALUE. These functions 
provide interfaces to the VMS utility routines CLI$PRESENT and CLI$GET_ 
VALUE, which retrieve information about the command string that invoked an 
image. For further information: 

• The VAX LISP/VMS System Access Guide describes the two VAX LISP 
functions. 

• The VMS Utility Routines Manual describes the two VMS routines. 

The remainder of this section outlines the specific procedures for writing a DCL 
command to invoke a LISP image. It also identifies the circumstances under 
which you are limited in defining command qualifier names. 


3.2.2.1 Defining a Command Without Qualifiers 

As an example of defining a DCL command without qualifiers or other 
command-line entities, you might write the following code in a file called MY- 
COMMANDS.CLD. This code defines a DCL command named EXPERT, which in¬ 
vokes the image EXPERT.EXE. The device and directory of this file are indicated 
by the logical name EXPERT$SYSTEM. 

DEFINE VERB EXPERT 

IMAGE "EXPERT$SYSTEM:EXPERT" 

Once the file MY-COMMANDS.CLD has been added to the appropriate command 
table, you can invoke EXPERT.EXE by typing EXPERT at the DCL prompt. 

Because the command EXPERT has no qualifiers, parameters, or keywords, the 
image EXPERT.EXE need not contain code that processes DCL command-line 
entities. 


3.2.2.2 Defining the Qualifiers /MEMORY, /RESUME, and /CSTACK 

A user-built LISP image always contains the Digital-provided code that checks 
for and processes the /MEMORY, /RESUME, and /CSTACK qualifiers in the 
command that invoked the image. You cannot alter the action of these qualifiers. 
Therefore, if you want your DCL command to take qualifiers named /MEMORY, 
/RESUME, or /CSTACK, you must define them in your CLD file exactly as follows: 

QUALIFIER MEMORY, NONNEGATABLE, VALUE(TYPE=$NUMBER,REQUIRED) 

QUALIFIER RESUME, VALUE(TYPE=$INFILE,REQUIRED) 

QUALIFIER CSTACK, NONNEGATABLE, VALUE(TYPE=$NUMBER,REQUIRED) 

For example, a CLD file that defines the command EXPERT with the qualifiers 
/MEMORY, /RESUME, and /CSTACK would look like this: 

DEFINE VERB EXPERT 

IMAGE "EXPERT$SYSTEM:EXPERT” 

QUALIFIER MEMORY, NONNEGATABLE, VALUE(TYPE=$NUMBER,REQUIRED) 
QUALIFIER RESUME, VALUE(TYPE=$INFILE,REQUIRED) 

QUALIFIER CSTACK, NONNEGATABLE, VALUE(TYPE=$NUMBER,REQUIRED) 

Since these three qualifiers are processed by Digital-provided LISP code, they 
behave in exactly the same way with the command EXPERT as they do with 
the command LISP. That is, /MEMORY allows you to invoke EXPERT.EXE 
with a specified amount of dynamic memory, /RESUME allows you to resume a 
suspended system that was created from within EXPERT.EXE, and /CSTACK 
allows you to invoke EXPERT.EXE with a specified size for the default control 
stack. 
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If you do not define these qualifiers in your CLD file, you cannot use them with 
the command EXPERT. You can, of course, continue to use them with the LISP 
command. 


3.2.2.3 Defining Other Digital-Defined Qualifiers 

In addition to /MEMORY, /RESUME, and /CSTACK, the LISP command takes 10 
qualifiers; they are processed by the VAX LISP function that is the default value 
of the define-lisp-system keyword :MAIN or the value of the define-lisp- 
system keyword : init-function. That is, the default entry point in a user-built 
system processes the following compiler-related qualifiers: 

/COMPILE /OPTIMIZE 

/LISTING /OUTPUT.FILE 

/MACHINE_CODE /WARNINGS 

and the following general-purpose qualifiers: 

/ERROR_ACTION /INTERACTIVE 

/INITIALIZE /VERBOSE 

If you have not specified a value for init-function or :MAIN in your call to 
define-lisp-system and you want to use any of these qualifiers when you invoke 
the system, you must define the qualifiers and their parameters exactly as they 
are defined in LISP$SYSTEM:LISPCLD. In addition, the VAX LISP Compiler 
must be present in your image for the entry point to process the compiler-related 
qualifiers. 


NOTE 

Except for the definitions of /MEMORY and /RESUME, the qualifier 
definitions in LISP$SYSTEM:LISP.CLD are not supported by Digital 
and may not be upward-compatible between versions. 

For example, the following CLD file defines the command EXPERT with the 
qualifier /INITIALIZE: 

DEFINE VERB EXPERT 

IMAGE M EXPERT$SYSTEM:EXPERT" 

QUALIFIER INITIALIZE, VALUE(TYPE=$INFILE,REQUIRED,LIST) 

The qualifier /INITIALIZE is defined as it is in LISP$SYSTEM:LISP.CLD. If 
EXPERT.EXE contains the default entry point, this qualifier behaves in the same 
way with the command EXPERT as it does with the command LISP 

If you have specified a value for -.main in your call to define-lisp-system, 
the Digital-provided code for processing the qualifiers other than /MEMORY, 
/RESUME, and /CSTACK is inaccessible in your image. You can then define any 
of these qualifier names in any way you like. You must, however, include user- 
written code in your image to check for and process each such qualifier that you 
define. 


3.2.2.4 Defining Other Command-Line Entities 

Apart from the Digital-defined qualifiers to LISP, you can define any command¬ 
line entity—qualifier, parameter, or keyword—in any way you like. For defining 
such entities, the values of : init-function and :MAIN are irrelevant. However, 
your image must always include user-written code for processing all such entities, 
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3.2.2.5 Summary of Restrictions on Command Definition 

The restrictions on defining command-line entities for a user-defined DCL com¬ 
mand to invoke a LISP image are: 

• The qualifiers /MEMORY, /RESUME, and /CSTACK are always processed by 
Digital-provided code. To use these qualifiers, you must define them as they 
are defined in LISP$SYSTEM:LISP.CLD. 

• The VAX LISP default entry-point function processes the remaining qualifiers 
to the command LISP. If your image includes the default entry point and you 
want to use these qualifiers, you must define them as they are defined in 
LISP$SYSTEM:LISP.CLD. Note that several of these qualifiers require the 
presence of the VAX LISP Compiler in the image. 

For example, the following CLD file defines the command EXPERT for invok¬ 
ing the image EXPERT$SYSTEM:EXPERT.EXE. (Assume that EXPERT.EXE 

contains the default entry point.) 

DEFINE VERB EXPERT 

IMAGE "EXPERT$SYSTEM:EXPERT" 

PARAMETER PI, PROMPT=”FILE(S)", VALUE(TYPE=$INFILE,LIST) 

QUALIFIER MEMORY, NONNEGATABLE, VALUE(TYPE=$NUMBER,REQUIRED) 
QUALIFIER INITIALIZE, VALUE(TYPE=$INFILE,REQUIRED,LIST) 

QUALIFIER QUICKJTRAVERSE, DEFAULT 

The command EXPERT takes one parameter and three qualifiers. 

• The parameter PI is to be processed by code you supply. You can define this 
parameter in any way you like. In this example, the command EXPERT 
prompts the user for one or more input file names. 

• The qualifier /MEMORY is to be processed by Digital-provided code. You must 
define the qualifier as shown. 

• Because the entry point to EXPERT.EXE is the default, the qualifier 
/INITIALIZE is to be processed by Digital-provided code. You must define 
the qualifier as shown. 

If the entry point is a function you supply, it must contain code to process 
/INITIALIZE. In this case, the qualifier could be defined in any way you like. 

• The qualifier /QUICK_TRAVERSE is to be processed by code you supply. You 
can define this qualifier in any way you like. 


3.2.3 Using the Digital-Defined Command LISP 

With certain restrictions, you can use the Digital-defined LISP command—along 
with any of its qualifiers—to invoke a user-built system. The major restriction on 
using the LISP command is that your executable file must be named LISP.EXE 
and must be in a directory pointed to by the logical name LISP$SYSTEM. 
LISP.EXE is the name of the Digital-supplied VAX LISP executable image, and 
the LISP command looks in LISP$SYSTEM for LISP.EXE. 

NOTE 

If you name your image file the same as the Digital-provided image file, 
take care that you do not accidentally delete the Digital-provided image 
file. 
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For example, if you use VAX LISP on a terminal instead of a workstation, and you 
want to dispense with the graphics functionality and the DECwindows interface 
in your development environment, you could write: 

(define-lisp-system "diskl:[smith.build]lisp.exe" 
rexclude '(:uis :decwindows)) 

The executable image that eventually results from this form contains all the 
functionality of the Digital-supplied VAX LISP except the graphics functionality 
and the DECwindows interface. Since the image has the same name as the 
Digital-supplied VAX LISP executable image, you can use the LISP command— 
with any of its qualifiers—to invoke the image you create. 

Before you can use the LISP command to invoke your image, you must redefine 
LISP$SYSTEM to point to DISK1:[SMITH.BUILD] so that the LISP command 
can locate the image. However, LISP$SYSTEM also contains other Digital- 
provided files (such as the documentation string text library, LISPDOC.TLB) 
that VAX LISP needs in order to run. Tb avoid copying these files into 
DISK1:[SMITH.BUILD], you can define the logical name LISP$SYSTEM to 
be a search list: 

$ SHOW LOGICAL LISP$SYSTEM 

f, LISP$SYSTEM" = "SYS$SYSROOT: [VAXLISP] " (LNM$SYSTEMTABLE) 

$ DEFINE LISP$SYSTEM DISKI:[SMITH.BUILD],SYS$SYSROOT:[VAXLISP] 

The LISP command now starts the image LISP.EXE in DISK1:[SMITH.BUILD]. 
LISP looks in SYS$SYSROOT:[VAXLISP] for files it needs but cannot find in 
DISK1:[SMITH.BUILD]. 

Restrictions on using the LISP command qualifiers are listed below under the set 
of LISP qualifiers to which they apply. 

• The qualifiers /MEMORY, /RESUME, and /CSTACK and their respective 
parameters: 

No further restrictions. Note that you need not create your own CLD file to 
use these two qualifiers with the Digital-defined LISP command. 

• The qualifiers /INITIALIZE, /VERBOSE, /INTERACTIVE, and /ERROR. 
ACTION and their respective parameters: 

RESTRICTION: Your image must include either the default entry point or 
user-written code that processes these qualifiers. 

• The qualifiers /COMPILE, /OPTIMIZE, /LISTING, /MACHINE.CODE, 
/OUTPUT.FILE, and /WARNINGS and their respective parameters: 

RESTRICTIONS: Your image must include either the default entry point or 
user-written code that processes these qualifiers. In either case, you must not 
exclude the VAX LISP Compiler from your image by supplying the :compiler 
keyword with :exclude. 
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